📝 CHANGELOG

All notable changes to the Talk to Your Docs RAG System.

[3.0.0] - 2026-01-01 - Langfuse v3 Migration

🔥 Breaking Changes

• Langfuse v3 Compatibility: Updated to support Langfuse v3 API

  • Removed dependency on langfuse_context (no longer available in v3)
  • Added compatibility layer for observe decorator imports
  • Implemented fallback methods for trace ID capture

• Python Version: Changed from Python 3.12 to Python 3.11

  • Updated Dockerfile to use python:3.11-slim
  • Updated CI/CD to test with Python 3.11

✨ New Features

Monitoring & Observability

• Prometheus Integration: Added metrics collection

  • New prometheus.yml configuration
  • Exposed /metrics endpoint on FastAPI
  • Track API latency, request count, errors

• Grafana Dashboards: Added visualization layer

  • Pre-configured Grafana service in docker-compose.yml
  • Default dashboards for API performance
  • Access at http://localhost:3000 (admin/admin)

Infrastructure

• Enhanced Docker Compose: Multi-service orchestration

  • Added prometheus service (port 9090)
  • Added grafana service (port 3000)
  • Improved networking between services
  • Volume management for persistent data

• Makefile Improvements: 60+ new commands

  • Docker management: make up, make down, make rebuild
  • Log viewing: make logs-api, make logs-streamlit
  • Database ops: make clean-db
  • K8s deployment: make k8s-deploy, make k8s-delete

Code Quality

• Graceful Error Handling: Better fallbacks for Langfuse API

  • Safe @observe decorator imports
  • Conditional trace ID capture
  • AttributeError handling for API differences

• Improved Logging: More informative debug messages

  • Emoji indicators for log levels
  • Structured error messages
  • Better trace ID warnings

🔧 Changed

Configuration

• src/config.py: Updated with new variables

  • Added TOP_K_RETRIEVAL = 50
  • Added TOP_K_RERANK = 7
  • Added API_HOST and API_PORT
  • Added MAX_CONCURRENT_REQUESTS

• .env.example: Expanded with all required variables

  • Langfuse v3 keys documented
  • Feature flags added
  • Performance tuning options

Core Components

• src/rag.py: Major refactoring for v3

  # Before (v2)
  from langfuse.decorators import observe, langfuse_context
  trace_id = langfuse_context.get_current_trace_id()
  
  # After (v3)
  from langfuse import Langfuse
  try:
      from langfuse import observe
  except Exception:
      from langfuse.decorators import observe
  
  # Safe trace ID capture
  trace_id = "unknown"
  try:
      if hasattr(self.langfuse, "get_current_trace_id"):
          trace_id = self.langfuse.get_current_trace_id()
  except Exception:
      pass

• src/app.py: Enhanced API endpoints

  • Added @observe decorator to /chat
  • Improved error messages
  • Better feedback handling with fallbacks

• src/ingestion.py: Updated imports

  • Compatibility layer for @observe
  • Better exception handling

Docker & Deployment

• Dockerfile: Optimized build process

  • Python 3.11 base image
  • Pre-cache FlashRank model
  • Better layer caching
  • Health check improvements

• docker-compose.yml: Complete rewrite

  • 5 services: qdrant, api, streamlit, prometheus, grafana
  • Proper health checks for all services
  • Volume management
  • Network isolation

• Dockerfile.qdrant: New custom Qdrant image

  • Added curl for health checks
  • Better for K8s deployments

CI/CD

• .github/workflows/ci.yml: Enhanced pipeline
  • Python 3.11 testing
  • Improved Qdrant health checks
  • Better test data ingestion
  • Smoke test for RAG queries
  • FastAPI integration tests
  • Evaluation report artifacts

📚 Documentation

New Files

• MIGRATION_TO_V3.md: Step-by-step migration guide
• prometheus.yml: Metrics configuration
• CHANGELOG.md: This file

Updated Files

• README.md: Complete rewrite
  • New sections for Prometheus/Grafana
  • Updated quickstart for v3
  • Expanded troubleshooting
  • Makefile command reference
  • Docker Compose documentation

🐛 Bug Fixes

• Fixed trace ID capture in v3 (no longer returns None)
• Fixed @observe import errors with compatibility layer
• Fixed Streamlit UI not starting due to import errors
• Fixed Docker health checks timing out
• Fixed Qdrant connection issues in CI

🔒 Security

• No environment variables stored in code
• All secrets via .env file
• Added .env.example template
• Docker secrets support documented

⚡ Performance

• Pre-download FlashRank model in Docker build
• Optimized layer caching in Dockerfile
• Lazy loading of heavy models in Streamlit
• Connection pooling for Qdrant

📊 Metrics & Monitoring

New Metrics Exposed

• http_requests_total - Total API requests
• http_request_duration_seconds - Latency histogram
• http_requests_in_progress - Active requests
• Custom RAG metrics (retrieval time, generation time)

Langfuse Traces

• Pipeline: rag_pipeline (main trace)
• Sub-traces: generate_multi_queries, rerank_docs, ingest_file
• API wrapper: api_chat (FastAPI endpoint)

🧪 Testing

• Added smoke tests in CI
• Added integration tests for API
• Added Qdrant health checks
• Test data ingestion in CI
• Evaluation pipeline in CI (conditional)

[2.0.0] - 2024-XX-XX - Previous Version

Features

• Langfuse v2 integration
• Python 3.12 support
• Basic Docker setup
• Streamlit UI
• FastAPI backend
• Qdrant vector store

Migration Summary

Files Changed (v2 → v3)

Modified:
  ✏️  README.md               (complete rewrite)
  ✏️  src/rag.py              (v3 compatibility)
  ✏️  src/app.py              (v3 compatibility)
  ✏️  src/ingestion.py        (v3 compatibility)
  ✏️  src/config.py           (new variables)
  ✏️  Dockerfile              (Python 3.11)
  ✏️  docker-compose.yml      (5 services)
  ✏️  Makefile               (60+ commands)
  ✏️  requirements.txt        (Langfuse v3)
  ✏️  .github/workflows/ci.yml (Python 3.11)

Added:
  ➕  MIGRATION_TO_V3.md
  ➕  CHANGELOG.md
  ➕  prometheus.yml
  ➕  Dockerfile.qdrant
  ➕  .env.example (expanded)

Unchanged:
  ✅  evaluation/evaluate.py
  ✅  k8s/*.yaml

Breaking Changes Summary

1. Import changes: Must use compatibility layer
2. Python 3.11: Must update local environment
3. Docker Compose: New services require env vars
4. trace_id capture: New methods required

Upgrade Steps

# 1. Pull latest code
git pull origin main

# 2. Update dependencies
pip install -r requirements.txt

# 3. Update environment
cp .env.example .env
# Edit .env with your credentials

# 4. Restart services
make rebuild

# 5. Verify
make logs
curl http://localhost:8000/health

Contributors

• Andriy Vlonha - Initial work and v3 migration

License

MIT License - See LICENSE file for details